Video Toaster 4.2

home *** CD-ROM | disk | FTP | other *** search

/ Video Toaster 4.2 / Video Toaster v4.2.iso / programs / documentation / lightwave / formatlwob.txt < prev next >

Wrap

Text File | 1995-05-18 | 17KB | 390 lines

LIGHTWAVE 3D OBJECT FILE FORMAT by Allen Hastings & Stuart Ferguson revised 11/28/94 Introduction LightWave 3D objects are stored as IFF files with a FORM type of LWOB. A FORM LWOB must contain a PNTS chunk, a SRFS chunk, and a POLS chunk. There may be zero or more SURF chunks anywhere in the file and up to one CRVS chunk. The POLS and CRVS chunks must be preceded by the PNTS chunk and the SRFS chunk. LightWave 2.0 also has the ability to save and load surface descriptions as FORM LWOB files that contain only a SURF chunk. This document explains the contents of each chunk and includes an annotated listing of a FORM LWOB as an example. PNTS Chunk This chunk contains a list of the X, Y, and Z coordinates of all the points in an object. Each coordinate is stored as a four byte floating point number in IEEE format. Therefore, the number of points in an object can be determined by dividing the size in bytes of the PNTS chunk by 12. By convention, the +X direction is to the right or east, the +Y direction is upward, and the +Z direction is forward or north. For models of real-world objects, the unit size is usually considered to be one meter. The coordinates are specified relative to an object's pivot point. See the LightWave Modeler manual for more information about LightWave 3D's geometric conventions. SRFS Chunk This chunk contains a list of the names of all the surfaces in an object (note that in LightWave 3D terminology, the word "surface" is defined as a set of attributes that describe the color and shading characteristics of a group of polygons). Each surface name appears as a null-terminated character string. If the length of the string (including the null) is odd, an extra null byte is added. Surface names should be read from the file until as many bytes as the chunk size specifies have been read. POLS Chunk This chunk contains a list of all the polygons in an object. Each entry consists of a short integer specifying the number of vertices in a polygon followed by that many short integers specifying the vertices themselves (as indices into the points list) followed by a short integer specifying which surface is used by the polygon (as an index into the surfaces list). The number of vertices in a polygon currently may vary from one to 200. The vertex list for each polygon should begin at a convex vertex and proceed clockwise as seen from the visible side of the polygon (LightWave 3D polygons are single-sided, except for those whose surfaces have the double- sided flag set). The points list in the PNTS chunk is numbered starting with zero and the surfaces list in the SRFS chunk is numbered starting with one (so that surface numbers can be made negative to signal the presence of detail polygons as explained below). Polygons should be read from the file until as many bytes as the chunk size specifies have been read. A negative surface number for a polygon indicates that the polygon has detail polygons (which are drawn on top of the main polygon and may be coplanar with it). In this case, the next number in the file is a short integer specifying how many detail polygons belong to the current polygon. This is followed by a list of those detail polygons, where each entry is of the same format as described above for regular polygons (except that the detail polygons cannot have details of their own). The list of regular polygons then resumes. To determine which surface is used by a polygon with a negative surface number, the absolute value of that number should be used. CRVS Chunks This chunk contains a list of all the spline curves in an object. Each entry consists of a short integer specifying the number of vertices in a curve followed by that many short integers specifying the vertices themselves in sequential order, followed by a short integer specifying which surface is used by the curve, followed by another short integer specifying bit-flags associated with the curve. If bit zero is set then the first point is a continuity control point, and if bit one is set then the last point is. The point and surface indices are as they are in the POLS chunk, except that curves cannot have details. Curves should be read from the file until as many bytes as the chunk size specifies have been read. SURF Chunks Each SURF chunk describes the surface attributes of a particular surface. These chunks begin with the name of the surface being described. The name is stored as a character string with either one or two trailing nulls (as explained in the SRFS chunk section). Following the name is a series of sub-chunks, which are like normal IFF chunks except that their sizes are specified by short integers instead of longs. It is likely that the variety of sub-chunks will grow as new surface attributes are added to the program, but any unknown sub-chunks may be skipped over in the usual IFF fashion. Sub-chunks should be read from the file until as many bytes as the chunk size specifies have been read. COLR Sub-Chunk This sub-chunk consists of three bytes that specify the red, green, and blue color components of the current surface, followed by a byte which is currently ignored and should be zero. A surface can therefore be any of 16,777,216 possible colors. FLAG Sub-Chunk This sub-chunk contains a short integer whose bits specify various options for the current surface. Currently only the nine least significant bits are used. The options that set bits indicate are (starting with the least significant bit): Luminous, Outline, Smoothing, Color Highlights, Color Filter, Opaque Edge, Transparent Edge, Sharp Terminator, Double Sided, and Additive (which is new for LW 3.0). Note that the two edge transparency bits should not both be set. LUMI, DIFF, SPEC, REFL, and TRAN Sub-Chunks Each of these sub-chunks contain a short integer that specifies the current surface's luminosity, diffuse, specular, reflection, or transparency settings (the LUMI sub-chunk is new for LW 3.0, and replaces the Luminous bit of the FLAG sub-chunk). A value of 256 in the file corresponds to a setting of 100% on the control panel. If any of these sub-chunks are absent for a surface, a value of zero is assumed for the corresponding parameter. GLOS Sub-Chunk This sub-chunk contains a short integer that specifies the glossiness of the current surface, and is only needed if the specular setting in the SPEC sub-chunk is non-zero. A value of 16 indicates low glossiness, 64 indicates medium glossiness, 256 indicates high glossiness, and 1024 indicates maximum glossiness (the maximum setting is new for LW 3.0). This parameter is related to the "specular exponent" used in many lighting models. RIMG Sub-Chunk This sub-chunk contains the filename (including any path the user may have specified) of the image to be used as a reflection map for the current surface. Once again, if the length of the string (including the terminating null) is odd, another null is added. If the last part of the string is " (sequence)", then the first part of the string specifies the prefix of an image sequence (the actual filename in this case is generated by appending a three digit frame number to the prefix when loading the image file for each frame). If the reflection setting in the REFL sub-chunk is non-zero but no RIMG sub-chunk is present, then the surface is assumed to reflect the sky and ground backdrop (or to use ray traced reflection if ray tracing is enabled). RSAN Sub-Chunk This sub-chunk contains a four byte IEEE floating point number that specifies the heading angle of the reflection map seam (expressed in degrees). This is new for LW 3.0. RIND Sub-Chunk This sub-chunk contains a four byte IEEE floating point number that specifies the current surface's refractive index, which is defined as the ratio of the speed of light in a vacuum to the speed of light in the material. Since light is fastest in a vacuum, this value should therefore be greater than or equal to 1.0. EDGE Sub-Chunk This sub-chunk contains a four byte IEEE floating point number that specifies the edge transparency threshold of the current surface. This value should lie between 0.0 and 1.0. SMAN Sub-Chunk This sub-chunk contains a four byte IEEE floating point number that specifies the maximum angle between two adjacent polygons that can be smooth shaded (expressed in degrees). Polygons with a greater angle between them will appear to meet at a sharp seam. This is new for LW 3.0. CTEX, DTEX, STEX, RTEX, TTEX, and BTEX Sub-Chunks The presence of one of these sub-chunks indicates that the current surface has a color, diffuse, specular, reflection, transparency, or bump texture. The contents of the sub-chunk is a character string (terminated by one or two nulls as usual) specifying the texture type as shown on the control panel. Once one of these sub-chunks is encountered within a SURF chunk, all subsequent texture-related sub-chunks (those described below) are considered to pertain to the current texture, until another CTEX, DTEX, STEX, RTEX, TTEX, or BTEX sub-chunk is read. Currently there may be zero or one of each of these sub-chunks (up to six textures) in each SURF chunk. TIMG Sub-Chunk This sub-chunk specifies the filename of the image (or the prefix of the image sequence) to be used for image texture mapping. See the description of the RIMG sub-chunk above for more details. TFLG Sub-Chunk This sub-chunk contains a short integer whose bits specify various options for the current texture. Currently only the seven least significant bits are used. The options that set bits indicate are (starting with the least significant bit): X Axis, Y Axis, Z Axis, World Coords, Negative Image, Pixel Blending, and Antialiasing. Note that only one of the three axis bits should be set. TSIZ, TCTR, TFAL, and TVEL Sub-Chunks These sub-chunks each consist of three IEEE four byte floating point numbers that specify the X, Y, and Z components of the current texture's size, center, falloff, or velocity. The TCTR, TFAL, and TVEL sub-chunks are only needed if the corresponding parameters are non-zero. TCLR Sub-Chunk This sub-chunk contains four bytes that specify the texture color for the current texture, which should be of the color-modifying variety (in other words, there should be a CTEX sub-chunk somewhere before this sub-chunk). The bytes are interpreted as described above in the COLR sub-chunk section. TVAL Sub-Chunk This sub-chunk contains a short integer that specifies the texture value of a diffuse, specular, reflection, or transparency texture, so it should appear somewhere after a DTEX, STEX, RTEX, or TTEX sub-chunk. A value of 256 in the file corresponds to a a setting of 100% on the control panel. TAMP Sub-Chunk This sub-chunk contains a four byte IEEE floating point number that specifies the amplitude of the current bump texture, so it should appear somewhere after a BTEX sub-chunk. A value of 1.0 is equivalent to a setting of 100% on the control panel. TFRQ Sub-Chunk This sub-chunk contains a short integer that specifies the number of noise frequencies or wave sources used by the current texture. TSP0, TSP1, and TSP2 Sub-Chunks These sub-chunks each contain a four byte IEEE floating point number that specifies one of the special texture type-specific parameters (such as Contrast, Turbulence, Wavelength, etc). Which sub-chunk is used to record a particular parameter depends on the order in which that parameter's button appears on the control panel. In the future there may be more than three of these per texture. Object File Example A simple object (with somewhat complex surfaces) is listed below to illustrate some of the features of a FORM LWOB. The object is an image-mapped bumpy square polygon in the XY plane with a shiny transparent yellow triangle as a detail polygon. Each line of the listing shows 16 bytes in hexadecimal form followed by their ASCII equivalents. The notes under each line should be read from left to right rather than top to bottom. 464F524D 0000019C 4C574F42 504E5453 FORM....LWOBPNTS 00000054 3F800000 3F800000 00000000 ...T?...?....... ^^^^^^^^ ^^^^^^^^ ^^^^^^^^ The X, Y, and Z coordinates of point number zero are 1.0, 1.0, and 0.0 (in IEEE format). ^^^^ There are 84 bytes in the PNTS chunk, so there are seven points in the object. BF800000 3F800000 00000000 3F800000 ....?.......?... BF800000 00000000 BF800000 BF800000 ................ 00000000 3F000000 BF000000 00000000 ....?........... 00000000 3F000000 00000000 BF000000 ....?........... BF000000 00000000 53524653 00000012 ........SRFS.... 53717561 72650000 54726961 6E676C65 Square..Triangle ^^^^ The surface name "Square" is terminated with two nulls to even out the number of bytes. 0000504F 4C530000 00180004 00010000 ..POLS.......... ^^^^ The first polygon has four vertices (which are points 1, 0, 2, and 3). 00020003 FFFF0001 00030005 00040006 ................ ^^^^ The detail polygon has three vertices (which are points 5, 4, and 6). ^^^^ One detail polygon follows. ^^^^ The first polygon's surface code is -1, so it uses surface number one ("Square") and has detail polygons. 00025355 52460000 00AE5371 75617265 ..SURF....Square ^^^^ ^^^^ This begins the description of the surface called "Square". ^^^^ The detail polygon uses surface number two ("Triangle"). 0000434F 4C520004 C8C8C800 464C4147 ..COLR......FLAG 00020000 44494646 00020100 43544558 ....DIFF....CTEX ^^^^^^^^ The next set of texture sub-chunks pertain to the surface's color texture. ^^^^ The "Square" surface's diffuse setting is 100% (256 out of 256). 0012506C 616E6172 20496D61 6765204D ..Planar Image M ^^^^ ^^^^^^^^ ^^^^^^^^ ^^^^^^^^ The color texture is planar mapping of the image in the IFF file "RAM:Laura". 61700000 54494D47 000A5241 4D3A4C61 ap..TIMG..RAM:La 75726100 54464C47 00020004 5453495A ura.TFLG....TSIZ ^^^^ The flag bits indicate that the image is to be projected along the Z axis. 000C4000 00003FC0 00003F80 00005443 ..@...?...?...TC ^^^^ ^^^^^^^^ ^^^^^^^^ ^^^^ The X, Y, and Z texture sizes are 2.0, 1.5, and 1.0. 4C520004 00000000 42544558 000E4672 LR......BTEX..Fr ^^^^^^^^ The next set of texture sub-chunks pertain to the "Square" surface's bump texture. 61637461 6C204275 6D707300 54464C47 actal Bumps.TFLG 0002000A 5453495A 000C3DCC CCCD3DCC ....TSIZ..=...=. ^^^^ The flag bits indicate that "Worlds Coords" is turned on. CCCD3DCC CCCD5441 4D500004 3FC00000 ..=...TAMP..?... ^^^^^^^^ The amplitude of the bumps is 150% (1.5 in IEEE format). 54465251 00020001 53555246 00000044 TFRQ....SURF...D ^^^^^^^^ This begins the description of the surface called "Triangle". ^^^^ The bump texture uses one frequency of noise. 54726961 6E676C65 0000434F 4C520004 Triangle..COLR.. F0B40000 464C4147 00020000 44494646 ....FLAG....DIFF ^^^^^^^^ The "Triangle" surface's color is yellow (240 red, 180 green, and 0 blue). 0002009A 53504543 000200CD 474C4F53 ....SPEC....GLOS ^^^^ The surface's specular setting is 80 % (205 out of 256). 00020100 5245464C 00020033 5452414E ....REFL...3TRAN ^^^^ The surface's reflection map setting is 20% (51 out of 256), but there is no RIMG sub- chunk, so the surface reflects the backdrop. ^^^^ The surface has a high glossiness (256). 00020066 ...f ^^^^ The surface is 40% transparent (102 out of 256). The "Triangle" surface has no textures, and there are no more surfaces to be defined, so the object file ends here.